Inside Macintosh: OpenDoc Programmer's Guide / Part 2 - Programming

Chapter 8 - Data Transfer

Writing to a Data-Transfer Object

You write data to a data-transfer object when the user cuts, copies, or drags data from your part or when you create or update the source of a link. This section discusses how to place that data into the data-transfer object.

This section does not discuss how your part handles cutting (or moving) differently from copying. Cutting involves removing data from your part, including possibly one or more frames of embedded parts. Removing an embedded frame is discussed in the section "Removing an Embedded Part".

Writing Intrinsic Content

Intrinsic content plus possibly one or more embedded parts is the most general configuration of data that you can place into a data-transfer object. If the data to be written consists of a combination of your part's intrinsic content plus embedded parts, you need to write your own intrinsic content, and you need to clone the embedded frames as well. If the data includes link sources or destinations, you need to clone those objects also. These are the basic steps to take, regardless of whether or not your intrinsic content is accompanied by embedded frames and other objects:

1. Gain access to the data-transfer object and prepare to write to it. (See, for example, the initial steps of "Copying or Cutting to the Clipboard".)
2. Start the cloning operation, as described in "Cloning".
3. Write your content to the data-transfer object. For intrinsic content, add a property with the name kODPropContents to the data-transfer object's content storage unit. Write your data into that property, in a value specified by the data format (part kind) of your intrinsic content.

   As you encounter persistent references to objects (embedded frames, link-source objects, link objects, auxiliary storage units, and so on), clone the objects to the data-transfer object by calling your draft's Clone method. Write persistent references to the newly cloned objects.

   Instead of writing actual data, you should if possible write a promise to the data-transfer object. See the section "Promises" for more information.

   If you promise the data, create a property with the name kODPropCloneKindUsed, containing a value of type kODCloneKind, in the content storage unit. Write the kind of cloning transaction you are using into that value. You can create this property instead of writing a clone kind into each promised value. Creating a kODPropCloneKindUsed property is a simple way to ensure that you fulfill promises for your intrinsic data using the correct clone kind.

4. If your editor supports other part kinds, write or promise additional versions of your data as separate values in that same property so that users can incorporate a version of your content into several different part kinds.
5. End the cloning operation.
6. If possible, add a suggested frame shape for the data (see "Frame Shape or Frame Annotation"), in case the data is embedded as a separate part in its destination.
7. If appropriate, create a link specification as described in the section "Link Specification".
8. Perform any closing tasks specific to the kind of data-transfer object you are writing to. (See, for example, the final steps of "Copying or Cutting to the Clipboard".)

In this process, any link sources or link destinations are correctly written to the data-transfer object, subject to the constraints listed in Table 8-3.)

If this is a cut rather than a copy operation, note the additional considerations listed in the section "Handling Cut Data"

Writing a Single Embedded Part

When the data that you place into the data-transfer object consists of a single frame of an embedded part--with no surrounding intrinsic content of the containing part (your part)--you must treat the operation as a special case. The identity of the data as a single, separate part must be preserved.

The content storage unit of the data-transfer object should end up with a duplicate of the embedded part; the nature of your part (the containing part) generally has nothing to do with the operation. However, you can write some data associated with the frame itself, if you wish; see step 4 of the following list.

In summary, you take these steps:

1. Gain access to the content storage unit of the data-transfer object and prepare to write to it. (See, for example, the initial steps of "Copying or Cutting to the Clipboard".)
2. Start the cloning operation, as described under "Cloning".

   In addition, create a property with the name kODPropCloneKindUsed, containing a value of type kODCloneKind, in the content storage unit. Write the kind of cloning transaction you are using into that value. (The embedded part, if it writes a promise, will use that value later, when fulfilling the promise.)

3. Clone the embedded part into the data-transfer object by calling your
   draft's Clone method. Unlike with writing intrinsic content, you do not add a kODPropContents property (the embedded part itself does that) or a kODPropSuggestedFrame property (you instead add a kODPropContentFrame property).

   Be sure to perform the cloning operation in this order:

   • Add a property with the name kODPropContentFrame to the data-transfer object's content storage unit. The presence of this property notifies the destination part that the data being transferred is a frame without surrounding intrinsic content, and also informs the embedded part (the part being cloned) that it can write a promise instead of its actual content.

     (It is important not to clone the frame yet. Wait until you've cloned the embedded part, or else the part itself will be cloned into the wrong storage unit.)

   • Clone the embedded part into the data-transfer object's content storage unit.
   • Clone the embedded part's frame into the data-transfer object's draft (into any storage unit other than the content storage unit). This cloning operation must occur after the embedded part is cloned.
   • Add a value of type kODWeakStorageUnitRef to the kODPropContentFrame property of the data-transfer object's content storage unit. Create a weak persistent reference from that value to the cloned frame. This reference allows a destination part, upon recognizing the kODPropContentFrame property, to locate the frame for the part in the data-transfer object.

4. Optionally, write any intrinsic data you want associated with the frame (such as a drop shadow or other visual adornment) as proxy content. Add a property (of type kODPropProxyContents) to the data-transfer object, and write your data into it as a value that your part recognizes. If the transferred part is subsequently pasted into a part that also recognizes that value and knows how to interpret it, those special characteristics of the frame can be duplicated.
5. If the embedded part is the entire source or destination of a link, you need to write additional proxy content, as described in "Writing Linked Content to Storage".
6. If appropriate, write a link specification into the data-transfer object, as described in the section "Link Specification".
7. Perform any closing tasks specific to the kind of data-transfer object you are writing to. (See, for example, the final steps of "Copying or Cutting to the Clipboard".)

If this is a cut rather than a copy operation, note the additional considerations listed in the section "Handling Cut Data"

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help